home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / C ++ / Applications / NeuroSim 1.0.2 / AGA Slider ƒ / Read Me
Encoding:
Text File  |  1997-03-22  |  12.1 KB  |  280 lines  |  [TEXT/CWIE]
  1. AGA Slider:    A demo of class CAGASlider v 1.4.2                    March 22, 1997
  2.     68K (Code works in PPC.)
  3.     CodeWarrior 9
  4.     PowerPlant
  5.  
  6. ================================================================================
  7.  
  8. AGA Slider is a project for demonstrating the CAGASlider class.
  9. It also includes CAGAProgressBar, CGAGroupBox and CBevelAttachment.
  10.  
  11. CAGASlider is a PowerPlant LControl that looks like a slider from
  12. the Apple Grayscale Appearance for System 7. It is not a CDEF.
  13.  
  14. Apple's docs on the AGA show you what things look like to the pixel,
  15. but, alas, they don't explain behaviors. I had to guess, mostly by 
  16. imitating the sliders in the system control panels. I have also added
  17. a reasonable black and white appearance.
  18.  
  19. Feel free to send me any comments, suggestions, and bug-reports to:
  20.   jennings@halcyon.com (James Jennings)
  21. Thanks to all those who have already written. The feedback was very helpful.
  22.  
  23. The AGA classes in this project are 
  24.     copyright © 1996-1997 by James Jennings. All rights reserved.
  25. This version of these classes may be freely used for non-commercial, shareware, 
  26. and commercial projects.
  27.  
  28. ================================================================================
  29.  
  30. Features of CAGASlider:
  31.     
  32.     What's New in v1.4.2
  33.         SetValue() will Draw() and Enable()/Disable() will Refresh() the slider. It 
  34.             was pointed out to me that this is the way most PowerPlant LControls work.
  35.         CGAGroupBox and CAGAProgresBar now also draw themselves as appropriate.
  36.         CAGAProgressBar was reworked slightly. See CProgressDemoWindow.
  37.     
  38.     What's New in v1.4.1
  39.         CAGASlider now detects and uses the background color that was drawn by the 
  40.             enclosing pane. The AGA specs don't actually specify a control's background.
  41.         Added some "#pragma unused" and "#include" directives.
  42.         The Constructor files now include the CTYP resources needed in CW11.
  43.     
  44.     What's New in v1.4
  45.         CAGAProgressBar.
  46.         Fixed the slider's disabled track fill color.
  47.         
  48.     What's New in v1.3.1:
  49.         Optimized so that it tracks the mouse better on slower machines.
  50.     
  51.     What's New in v1.3:
  52.         "Ghost" indicator now slides under the real indicator. (Like the Speech control
  53.             panel does.) (Thanks to Sarwat Khan for pointing out the obvious.)
  54.         
  55.     What's New in v1.2: 
  56.         The disabled state now matches the specification on the 
  57.             September 1996 Developer CD.
  58.         The black and white disabled state is now drawn with a gray pattern.
  59.         This distribution also includes a Group Box class (CGAGroupBox) based on 
  60.         LGroupBox, and CBevelAttachment which allows you to add Grayscale Appearance
  61.             style bevels to any pane using Constructor 2.2 or later.
  62.  
  63.     What's New in v1.1: 
  64.         The direction of increasing values can be changed in Constructor.
  65.     
  66.     Mouse down in the indicator shows a "pressed" indicator.
  67.     As indicator is dragged, the pressed indicator doesn't move and a "ghost" 
  68.         indicator follows the mouse.
  69.     The ghost indicator slides under the pressed indicator.
  70.     Clicking on the "track" jumps the indicator to that position.
  71.     When the mouse is released, the real indicator moves to the ghost's last position.
  72.     When the mouse is dragged away from the track, the ghost disappears. (Aborting.)
  73.     Horizontal and vertical sliders are centered in the pane. (Needs >=16 pixel width.)
  74.     "Pointing" sliders (which have tick marks) are aligned to the side of the pane away 
  75.         from the pointer and the tick marks. (Needs >=25 pixel width.)
  76.     Sliders are drawn correctly when Disabled().
  77.     Uses StOffscreenGWorld for flicker-free tracking.
  78.     Looks reasonable on black and white screens.
  79.     Looks reasonable when split across two monitors of different pixel depths. (Although,
  80.         since I only have one monitor myself, this hasn't been tested as much as I'd like.)
  81.     Has a "continuous broadcast" option for "active" sliders.
  82.  
  83. Limitations:
  84.     Doesn't have value labels. If you add your own (with an LCaption, say)
  85.     be sure to gray them out when the CAGASlider is disabled.
  86.     
  87.     When disabled and on a black and white screen, CGAGroupBox will draw the text 
  88.     using a gray pattern. This will render the text illegible unless you use a font 
  89.     like Chicago 12 (which the AGA standard recommends.)
  90.     
  91.     Although you can use CBevelAttachment to add a "bevel" to an LEditField, 
  92.     (as I've done in this demo), note that it doesn't change when the field is disabled. 
  93.     CBevelAttachment requires CodeWarrior 9 or later.
  94.  
  95. ================================================================================
  96.  
  97. CAGASlider's CPPb resource (for Constructor) should define these members:
  98.  
  99.     Direction:    (Int32, viewed as Text)
  100.         Values: hori, vert, nort, sout, east, west, prop
  101.         Chooses the indicator type. 
  102.         nort, sout, east, west refer to the compass direction of "pointy" indicators.
  103.         'prop' chooses hori or vert depending on the pane proportions.
  104.         Note: These values are not stored. They are converted into an enumerated 
  105.             type in the CAGASlider constructor.
  106.     Number of Tick Marks: (Uint16)
  107.         Values:
  108.             0: Don't show tick marks.
  109.             1: Show one tick mark for each allowed value of LControl::mValue.
  110.             n > 1: Show n tick marks (n-1 intervals).
  111.         Note: Number of Tick Marks is ignored for hori and vert types.
  112.     Continuous Broadcast: (Boolean)
  113.         Values:
  114.             false: BroadcastMessage() is called only when the slider is released (on mouseUp).
  115.             true:  BroadcastMessage() is called every time the value changes during a drag.
  116.     mMinValue is at Bottom or Right: (Boolean)
  117.         Values:
  118.             false: mValue == mMinValue when the slider is at the top 
  119.                 (for vertical sliders) or the left (for horizontal sliders). 
  120.                 This is the way standard scrollbars behave.
  121.             true: mValue == mMinValue when the slider is at the bottom 
  122.                 (for vertical sliders) or the right (for horizontal sliders). 
  123.                 This may be more intuitive for some vertical sliders. ("up is more")
  124.  
  125. There is also a file called CAGASlider1.1.CPPb which defines CAGASlider for Constructor.
  126. It has been hacked so that the Direction appears as a pop-up menu. 
  127. The best way to use it is to place it in the same folder with Constructor 
  128. so that Constructor (v2.2 or later) will load it on startup.
  129.  
  130. *** Note: Constructor 2.2 cannot edit CAGASlider1.1.CPPb without crashing. ***
  131.           Constructor 2.3 (CW10) will politely decline to edit it.
  132.           Constructor 2.4 doesn't show the directions as a pop-up menu at all. (*sigh*)
  133.  
  134. If you need a CPPb that you can edit, use the file "CAGASlider1.1.CTYP (no popup)"
  135. found in the "(Backward compatibility)" folder.
  136.  
  137. ================================================================================
  138.  
  139. CAGAProgressBar's CPPb/CTYP resource (for Constructor) doesn't define any new members.
  140.  
  141. "Indeterminant" Progress Bars:
  142.     Set the Minimum == the Maximum in Constructor.
  143.         (Or call SetMinValue() and SetMaxValue() with the same argument.)
  144.     Indeterminant bars are updated every time SetValue() is called, 
  145.         although the argument of SetValue() is ignored
  146.     You can keep from drawing too often by calling SetValueDelayedDrawing()
  147.  
  148. There is a file called CAGAProgressBar.CTYP which defines CAGAProgressBar for Constructor.
  149.  
  150. ================================================================================
  151.  
  152. CGAGroupBox's CPPb/CTYP resource (for Constructor) should define one member:
  153.     
  154.     Primary/Secondary: (Boolean)
  155.         Values:
  156.             true: Draw a "primary" group box.
  157.             false: Draw a "secondary" group box. (For use inside a primary group box.)
  158.  
  159. There is a file called CGAGroupBox.CTYP which defines CGAGroupBox for Constructor.
  160.  
  161. ================================================================================
  162.  
  163. CBevelAttachment's CPPb/CTYP resource (for Constructor) should define these members:
  164.  
  165.     Bevel In: (Boolean)
  166.         If true, draw a bevel that makes the pane look recessed. Otherwise,
  167.         draw a bevel that makes the pane look raised.
  168.     Width: (Int16)
  169.         How wide to draw the bevel. Usually 1 or 2.
  170.         If you make this negative, the bevel will be drawn outside the the edge 
  171.             of the pane. Note that this might not always get updated properly.
  172.     Fill with white: (Boolean)
  173.         If true, erase the center of the view with white. If false, do nothing.
  174.  
  175. There is a file called CBevelAttachment.CTYP which defines CBevelAttachment for Constructor.
  176. Note that Attachments are not supported by Constructor before version 2.2 (CW9).
  177.  
  178. ================================================================================
  179.  
  180. To add CAGASliders to your project:
  181.  
  182.     To a PowerPlant "Starter" project you will need to add the files:
  183.         CAGASlider.cp
  184.         AGA Slider Parts PICTs.rsrc
  185.         UGrayscaleAppearance.cp
  186.         UGWorld.cp
  187.     You will also need:    (in your project folder)
  188.         CAGASlider.h    
  189.         UGrayscaleAppearance.h
  190.     and:    (in Constructor's folder)
  191.         CAGASlider.CTYP
  192.     You will also need to register the ClassCreatorFunc in your app's constructor.
  193.  
  194. To add CAGAProgressBar to your project:
  195.  
  196.     To a PowerPlant "Starter" project you will need to add the files:
  197.         CAGAProgressBar.cp
  198.         AGA Progress Bar Parts.rsrc
  199.         UGrayscaleAppearance.cp
  200.         UGWorld.cp
  201.     You will also need:    (in your project folder)
  202.         CAGAProgressBar.h    
  203.         UGrayscaleAppearance.h
  204.     and:    (in Constructor's folder)
  205.         CAGAProgressBar.CTYP
  206.     You will also need to register the ClassCreatorFunc in your app's constructor.
  207.  
  208. To add CGAGroupBox to your project:
  209.  
  210.     To a PowerPlant "Starter"  project you will need to add the files:
  211.         LGroupBox.cp
  212.         CGAGroupBox.cp
  213.         UGrayscaleAppearance.cp
  214.     You will also need:
  215.         LGroupBox.h
  216.         CGAGroupBox.h
  217.         UGrayscaleAppearance.h
  218.         CGAGroupBox.CTYP (in Constructor's folder)
  219.     You will also need to register the ClassCreatorFunc in your app's constructor.
  220.  
  221. To add CBevelAttachment to your project:
  222.  
  223.     To a PowerPlant "Starter"  project you will need to add the files:
  224.         CBevelAttachment.cp
  225.         UGrayscaleAppearance.cp
  226.     You will also need:
  227.         CodeWarrior release 9 or later.
  228.         CBevelAttachment.h
  229.         UGrayscaleAppearance.h
  230.         CBevelAttachment.CTYP (in Constructor's folder)
  231.     You will also need to register the ClassCreatorFunc in your app's constructor.
  232.  
  233. ================================================================================
  234.  
  235. Programming Notes:
  236.  
  237. CAGASlider inherits from LControl and UGrayscaleAppearance.
  238. CAGAProgressBar inherits from LControl and UGrayscaleAppearance.
  239. CGAGroupBox inherits from LGroupBox and UGrayscaleAppearance.
  240. CBevelAttachment inherits from LAttachment and UGrayscaleAppearance.
  241.  
  242. UGrayscaleAppearance encapsulates the AGA color definitions and a few utility functions.
  243.  
  244. I set the background color of the Demo's windows to gray by setting its "content" color 
  245. in ResEdit. This adds a 'wctb' resource. There is no code in the project that draws 
  246. the background color for the whole window, just for the sliders.
  247.  
  248. The slider allocates some memory for holding the indicator (thumb) images. These
  249. images are shared by all sliders in the application, and normally hang around 
  250. until the application quits. If you want to be really fanatic about freeing up 
  251. memory (it's only a few K), you can call CAGASlider::Purge().
  252.  
  253. The progress bar allocates some memory for holding fill patterns and such. These 
  254. graphics are shared by all progress bars in the application, and normally hang around 
  255. until the application quits. If you want to be really fanatic about freeing up 
  256. memory (it's only a few K), you can call CAGAProgressBar::Purge().
  257.  
  258. I deliberately made the slider so that the indicator "snapped to" the allowed
  259. values of the slider. If you want a smoother feel, try increasing the range
  260. of the slider values until it looks smooth, and then adjust the result of GetValue()
  261. before you use it. For an example, note that the demo has some sliders with 10 
  262. intervals, and some with 100 intervals.
  263.  
  264. When I switched from Apple's April 96 specification to the Sept 96 specification, I 
  265. made it conditionally compiled. To revert to the April specification:
  266.     #define AGA_VERSION 1 in both CAGASlider and CGAGroupBox
  267.     Replace the file "AGA Slider Parts PICTs.rsrc" with "AGA Slider Parts PICTs Apr.rsrc"
  268.  
  269. Progress Bars are drawn 14 pixels high. In Constructor, set the pane height to 
  270. at least 14. More doesn't hurt. Less will trigger some debugging code.
  271.     
  272. CBevelAttachment requires Codewarrior release 9 or better.
  273. To compile the demo under CW8 or earlier:
  274.     1) replace the file "AGA Slider.rsrc" with "AGA Slider.rsrc (no bevel)"
  275.     2) remove the file CBevelAttachment.cp from the project.
  276.     3) remove the references to CBevelAttachment that appear in AGASliderApp.cp
  277.  
  278. James Jennings
  279. jennings@halcyon.com
  280.